Skip to content

chore(deps): switch host transport to @parity/truapi - #23

Open
illegalcall wants to merge 2 commits into
paritytech:mainfrom
illegalcall:chore/switch-to-truapi
Open

chore(deps): switch host transport to @parity/truapi#23
illegalcall wants to merge 2 commits into
paritytech:mainfrom
illegalcall:chore/switch-to-truapi

Conversation

@illegalcall

@illegalcall illegalcall commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Closes #20

Drops @novasamatech/host-api(-wrapper) and bumps product-sdk-host to ^0.14.1 and product-sdk-signer to ^0.11.1. The host transport is now @parity/truapi, pulled in via product-sdk-host. No source changes needed; level docs referencing the retired wrapper are updated.

Typecheck and build pass. Quest run-through in Desktop still pending.

Drop @novasamatech/host-api(-wrapper); bump product-sdk-host to ^0.14.1
and product-sdk-signer to ^0.11.1 (truAPI comes in via product-sdk-host).
No source changes required. Refresh level docs that referenced the
retired wrapper.

Closes paritytech#20
@socket-security

socket-security Bot commented Jul 24, 2026

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Updated@​parity/​product-sdk-signer@​0.6.3 ⏵ 0.11.178 +110072 +199 +2100
Updated@​parity/​product-sdk-host@​0.8.0 ⏵ 0.14.178 +110073 +299 +2100

View full report

@illegalcall

Copy link
Copy Markdown
Contributor Author

@ReinhardHatko can you please review, i dont have access to add you as a reviewer.

@ReinhardHatko ReinhardHatko left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this — right change, and the version choices check out. I verified product-sdk-host@0.14.1, product-sdk-signer@0.11.1 and truapi@0.5.1 against the npm registry: those are the current latest, so this isn't bumping to an arbitrary point.

What checks out

  • Real dependency-tree win. Dropping the two @novasamatech/* direct deps removes ~60 transitive packages: all of @polkadot/api@16.5.6, extension-inject, util-crypto/wasm-crypto/wasm-bridge, smoldot + @substrate/connect, nock, mock-socket, node-fetch with its fetch-blob/formdata-polyfill chain, bn.js. For a tutorial whose stated goal is first deploy in ~15 minutes, a materially faster npm install is on-target — and it shrinks the supply-chain surface.
  • The bun.lock regeneration fixes pre-existing drift. main's package.json already carried overrides: { "@polkadot-api/json-rpc-provider": "0.2.0" }; main's bun.lock did not. This PR re-adds it. That's a fix, not a new pin — worth calling out so it doesn't read as an unexplained addition.
  • "No source changes needed" is credible — the import surface is only src/utils.ts:2-7 (SignerManager/HostProvider/DevProvider) and src/App.tsx:2 (isInsideContainerSync).
  • nanoid shifting 5.1.11 → 3.3.12 at top level is just postcss's copy getting hoisted once host-api stopped pulling v5. Nothing in src/ uses it — not a regression.

Two things I'd want before merge

1. A stale runtime requirement the doc sweep missed — docs/levels/level-1-local-challenger.md:35-36

A Polkadot hostdot.li in a browser, or the Polkadot Desktop app (≥ 0.7.5). The host ships the host-api 0.8.x wire protocol the current SDK targets.

This contradicts the PR's own premise, and it's not just prose — it's a version gate. It tells developers Desktop ≥ 0.7.5 is sufficient. If truapi 0.5.x speaks a different wire protocol than host-api 0.8.x, someone on 0.7.5 hits a host-connect failure on the very first step of Level 1 while the doc confirms their version is fine.

Since this is the doc-sweep PR, this line belongs in it: please verify the actual minimum Desktop version under truapi and update both the version number and the protocol sentence.

2. The one thing that changed is the one thing not exercised

The PR body notes the quest run-through is still pending. That's the gap I'd close before merging, because:

  • These are 0.x packages, where minor bumps are breaking by convention — and this is 0.6.3 → 0.11.1 (5 minors) and 0.8.0 → 0.14.1 (6 minors), on precisely the packages that own the host handshake.
  • tsc -b && vite build exercises none of that path, and there's no test suite or CI in the repo (.github/ contains only copilot-instructions.md), so "typecheck and build pass" can't cover it.
  • At-risk surface is specifically new HostProvider({ productAccount: { dotNsIdentifier, derivationIndex: 0 } }) (src/utils.ts:19-21) and isInsideContainerSync().

Suggested minimum: clean npm installnpm run build → Desktop host connect → account select → one signature → one pg deploy. A broken handshake here doesn't degrade the tutorial, it stops Level 1 dead for every attendee.

Worth checking

3. This puts the repo at odds with the SDK skills setup.sh injects every session

setup.sh refetches .claude/skills/ from product-sdk@main at every session start, and those skills still describe the pre-truapi world:

  • references/gotchas.md G11 states that @parity/product-sdk-host re-exports getTruApi/getPreimageManager from @novasamatech/host-api-wrapper, and that it "remains as a transitive dep".
  • SKILL.md:37,122,182,309 repeat it. truapi appears nowhere in those skills.

After this PR, host-api-wrapper is absent from the tree entirely — so every session hands the assistant two conflicting doc sets, with the stale one refreshed automatically and not editable from here. Could you file an upstream product-sdk issue to update G11 + those SKILL.md lines and link it from this PR? Otherwise the tutorial's own guidance quietly loses to the auto-fetched version.

4. A substitution that may have turned a true warning false — docs/levels/level-4-multiplayer.md:125

Don't go lower-level than @parity/product-sdk-statement-store (e.g. @parity/truapi's raw statement store)

truapi@0.5.1's only dependencies are @noble/hashes, neverthrow and scale-ts — that profile reads as a wire-protocol codec. host-api-wrapper plausibly did expose a statement-store surface; truapi may not. If it doesn't, this went from a real warning to a nonexistent one. Either confirm truapi exposes it, or just drop the parenthetical — the advice stands without it.

Nits

  • docs/levels/level-1-local-challenger.md:110-111 — the in-place substitution left a ragged wrap (@parity/truapi is shorter than what it replaced); these files are consistently ~80-col prose-wrapped. Worth a reflow.
  • ^0.14.1 on a 0.x package resolves to <0.15.0, while docs/levels/00-overview.md:19-21 and level-1:45 both say "always use the latest — do NOT pin" / npm install <pkg>@latest. Correct today, but given 0.8 → 0.14 in a single bump, the manifest and that advice will diverge again quickly. Not for this PR — but maybe worth a scheduled bump check rather than another manual sweep.
  • The product-sdk skills recommend "@polkadot-api/json-rpc-provider": "^0.2.0" (caret); this repo pins exact 0.2.0. Pre-existing and harmless, but easy to align while you're here.

Follow-ups, not this PR

  • bun.lock is committed but npm is the install path. .gitignore:6 ignores package-lock.json, while setup.sh:37, README.md:65 and docs/levels/00-overview.md:21 all use npm — so bun.lock governs nothing developers actually receive. The overrides drift this PR fixes is evidence it rots silently. Either add a minimal CI job (npm install && npm run build, plus a bun install --frozen-lockfile check if bun is intended) or drop bun.lock.
  • Cross-repo consistency: paritytech/Rock-Paper-Scissors — the reference implementation with all four levels working — is still on @novasamatech/host-api@^0.8.10 and has no truapi issue open (its #19/#20 mirror this repo's #21/#22, but there's no counterpart to #20). Once this merges, the tutorial and the reference app will be on two different host transports. Worth opening the mirror issue there.

Security

No concerns. @parity/truapi, @parity/result and @parity/product-sdk-errors are first-party; neverthrow and scale-ts were already in the tree. Removing @polkadot/extension-inject drops a browser-extension injection surface the tutorial never used. Net reduction in third-party code.


Summary: correct change, correct versions, good cleanup. Blocking on the Desktop run-through (2) and the level-1:35-36 version gate (1) — both small. 3 and 4 are quick verifications; the rest can trail.

@illegalcall

Copy link
Copy Markdown
Contributor Author

Addressed the doc items:

  • level-1: dropped the stale host-api 0.8.x wire protocol / ≥ 0.7.5 version gate; it now says a current Polkadot Desktop connecting through the truAPI transport. I couldn't verify the exact minimum Desktop version under truAPI, so I removed the specific number rather than assert a possibly-wrong one; worth confirming with the host team.
  • level-4: dropped the @parity/truapi's raw statement store parenthetical (truapi 0.5.1 ships only codec deps, so that surface likely doesn't exist); the advice stands without it.
  • reflowed the level-1 wrap nit.
  • filed the upstream skills issue: SDK skills still describe the pre-truAPI host transport (G11, SKILL.md) product-sdk#274 (G11 + SKILL.md still describe the pre-truAPI transport).

Left the @polkadot-api/json-rpc-provider pin exact rather than caret: it was pinned to 0.2.0 in #7 specifically to fix an npm build, so a caret risks regressing that. The Desktop quest run-through is still pending on my side.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Switch to truAPI (retire the triangle-js-sdks host transport)

2 participants